<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Syscalls &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Skulpt API / Pytch environment" href="skulpt-pytch-environment.html" />
    <link rel="prev" title="Hat blocks" href="hat-blocks.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="syscalls">
<h1>Syscalls<a class="headerlink" href="#syscalls" title="Link to this heading">¶</a></h1>
<p>When a Pytch program needs the services of the Pytch runtime, it uses a
‘syscall’. This is implemented with the Skulpt suspension mechanism.
Most Pytch syscalls return a Skulpt suspension, which makes the
<code class="docutils literal notranslate"><span class="pre">resume()</span></code> call return a Suspension rather than a Python value. The
suspension captures the ‘continuation’ of that computation.</p>
<p>Most syscalls cause a thread to yield. The approach is motivated to some
extent by the Linux kernel’s top-half / bottom-half interrupt
processing. It did not seem very clean to have the syscall itself
rummage around in the live project or its thread groups. For example, we
don’t know which Pytch Thread object we’re part of when we hit the
syscall in Python.</p>
<p>Most syscalls return <code class="docutils literal notranslate"><span class="pre">None</span></code> to Python when they’ve been dealt with on
the Pytch side, usually after a suspension has <code class="docutils literal notranslate"><span class="pre">resume()</span></code>’d. (We
could explore other approaches, e.g., a broadcast could return to Python
the list of created threads.) The ‘is-touching’ syscall returns a Python
bool giving the answer to the is-touching question.</p>
<p>If a syscall itself throws a JavaScript error, that error is captured
and then eventually raised when the Python-level computation resumes.
This is achieved by the Pytch suspension storing the error, which is
then thrown in the suspension’s <code class="docutils literal notranslate"><span class="pre">resume()</span></code> method.  See
<code class="docutils literal notranslate"><span class="pre">new_pytch_suspension()::resume()</span></code> and <code class="docutils literal notranslate"><span class="pre">Thread.one_frame()</span></code> for
details.</p>
<p>We create a new type “Pytch” of Skulpt suspension. Use “subtype” to say
which syscall was invoked; add a new suspension property “subtype_data”
for any arguments the syscall requires.</p>
<p>DOC TODO: Adjective to distinguish the two types of syscall? Is there
also a distinction between syscalls which yield and those that don’t?</p>
<p>Many syscalls (DOC TODO: ‘all’?) replace the thread’s stored suspension
with the newly-created one, so that thread’s execution resumes from the
point it invoked the syscall.</p>
<p>Some syscalls can result from more than one Python-level function
call.  For example, the same syscall handles both <code class="docutils literal notranslate"><span class="pre">broadcast()</span></code> and
<code class="docutils literal notranslate"><span class="pre">broadcast_and_wait()</span></code> functions, distinguishing between them via an
argument.</p>
<p>In the below list, the syscall label (“kind”) string is given,
followed by the user-level function/s which invoke it.</p>
<dl class="simple">
<dt>next-frame — <code class="docutils literal notranslate"><span class="pre">yield_until_next_frame()</span></code></dt><dd><p>Pauses execution for this frame, but resumes immediately next time
<code class="docutils literal notranslate"><span class="pre">one_frame()</span></code> runs.</p>
</dd>
<dt>broadcast — <code class="docutils literal notranslate"><span class="pre">broadcast()</span></code>, <code class="docutils literal notranslate"><span class="pre">broadcast_and_wait()</span></code></dt><dd><p>Launches new thread group for any methods handling the given
message.  The ‘and-wait’ variant also marks the calling thread as
awaiting-thread-group-completion.</p>
</dd>
<dt>play-sound — <code class="docutils literal notranslate"><span class="pre">start_sound()</span></code>, <code class="docutils literal notranslate"><span class="pre">play_sound_until_done()</span></code></dt><dd><p>Requests that the given sound be started.  For the
<code class="docutils literal notranslate"><span class="pre">play_sound_until_done()</span></code> variant, puts the thread to sleep
awaiting-sound-completion.</p>
</dd>
<dt>wait-seconds — <code class="docutils literal notranslate"><span class="pre">wait_seconds()</span></code></dt><dd><p>Pauses execution for the given amount of time, converted into frames
at 60fps.</p>
</dd>
<dt>register-instance — <code class="docutils literal notranslate"><span class="pre">create_clone_of()</span></code></dt><dd><p>Adds the given Python instance to the Project, such that methods can
be launched on it via Pytch events.</p>
</dd>
<dt>unregister-running-instance — <code class="docutils literal notranslate"><span class="pre">delete_this_clone()</span></code></dt><dd><p>Removes the given Python instance from the Project.  It still exists
as a Python object, but will no longer respond to Pytch events.</p>
</dd>
<dt>ask-and-wait-for-answer — <code class="docutils literal notranslate"><span class="pre">ask_and_wait()</span></code></dt><dd><p>Requests that the given question be asked, and puts the thread to
sleep awaiting-answer-to-question.</p>
</dd>
<dt>show-object-attribute — <code class="docutils literal notranslate"><span class="pre">show_variable()</span></code></dt><dd><p>Add an attribute of an object to the list of “attribute watchers”;
these report the the value of the given attribute back to the client
each frame, as a <a class="reference internal" href="rendering.html"><span class="doc">rendering instruction</span></a>.</p>
</dd>
<dt>hide-object-attribute — <code class="docutils literal notranslate"><span class="pre">hide_variable()</span></code></dt><dd><p>Remove the attribute watcher corresponding to this object and
attribute.</p>
</dd>
<dt>stop-all-threads — <code class="docutils literal notranslate"><span class="pre">stop_all()</span></code></dt><dd><p>Programmatically press the “red stop” button.</p>
</dd>
</dl>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1"><a class="reference internal" href="../user/index.html">Writing Pytch programs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../developer.html">Developer documentation</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../developer/development-setup.html">Development setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/design-overview.html">Design overview</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html">VM</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="overview.html">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="integration-with-client.html">Integration with client</a></li>
<li class="toctree-l3"><a class="reference internal" href="based-on-skulpt.html">Skulpt: Python / JavaScript bridge</a></li>
<li class="toctree-l3"><a class="reference internal" href="project.html">Project</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor.html">Actor: Sprite and Stage</a></li>
<li class="toctree-l3"><a class="reference internal" href="actor-registration.html">Actor-class registration</a></li>
<li class="toctree-l3"><a class="reference internal" href="threading-model.html">Threading model</a></li>
<li class="toctree-l3"><a class="reference internal" href="hat-blocks.html">Hat blocks</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Syscalls</a></li>
<li class="toctree-l3"><a class="reference internal" href="skulpt-pytch-environment.html">Skulpt API / Pytch environment</a></li>
<li class="toctree-l3"><a class="reference internal" href="testing.html">Testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="ide-web-app.html">Web-app</a></li>
<li class="toctree-l3"><a class="reference internal" href="rendering.html">Rendering</a></li>
<li class="toctree-l3"><a class="reference internal" href="hit-detection.html">Collision and click detection</a></li>
<li class="toctree-l3"><a class="reference internal" href="clones.html">Clones</a></li>
<li class="toctree-l3"><a class="reference internal" href="sounds.html">Sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="tutorials.html">Tutorials</a></li>
<li class="toctree-l3"><a class="reference internal" href="docstrings.html">Docstrings</a></li>
<li class="toctree-l3"><a class="reference internal" href="attribute-watchers.html">Watching object attributes</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../webapp/developer/index.html">Webapp</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../medialib/developer/index.html">Media library</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../developer/index.html">Website</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../build-tools/index.html">Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../source-build.html">Source and build information</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../releases/changelog.html">Changelog</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>